{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# HPO with dask-ml and cuml\n",
    "\n",
    "## Introduction\n",
    "\n",
    "&emsp; &emsp; &emsp; [Hyperparameter optimization](https://cloud.google.com/ai-platform/training/docs/hyperparameter-tuning-overview) is the task of picking the values for the hyperparameters of the model that provide the optimal results for the problem, as measured on a specific test dataset. This is often a crucial step and can help boost the model accuracy when done correctly. Cross-validation is often used to more accurately estimate the performance of the models in the search process. Cross-validation is the method of splitting the training set into complementary subsets and performing training on one of the subsets, then predicting the models performance on the other. This is a potential indication of how the model will generalise to data it has not seen before.\n",
    "\n",
    "Despite its theoretical importance, HPO has been difficult to implement in practical applications because of the resources needed to run so many distinct training jobs.\n",
    "\n",
    "The two approaches that we will be exploring in this notebook are :\n",
    "\n",
    "\n",
    "#### 1. GridSearch\n",
    "\n",
    "&emsp; &emsp; &emsp; As the name suggests, the \"search\" is done over each possible combination in a grid of parameters that the user provides. The user must manually define this grid.. For each parameter that needs to be tuned, a set of values are given and the final grid search is performed with tuple having one element from each set, thus resulting in a Catersian Product of the elements.\n",
    "\n",
    "&emsp; &emsp; &emsp;For example, assume we want to perform HPO on XGBoost. For simplicity lets tune only `n_estimators` and `max_depth`\n",
    "\n",
    "&emsp; &emsp; &emsp;`n_estimators: [50, 100, 150]`\n",
    "\n",
    "&emsp; &emsp; &emsp;`max_depth: [6, 7, ,8]`\n",
    "    \n",
    "&emsp; &emsp; &emsp; The grid search will take place over |n_estimators| x |max_depth| which is 3 x 3 = 9. As you have probably guessed, the grid size grows rapidly as the number of parameters and their search space increases.\n",
    "\n",
    "#### 2. RandomSearch\n",
    "\n",
    "\n",
    "&emsp; &emsp; &emsp; [Random Search](http://www.jmlr.org/papers/volume13/bergstra12a/bergstra12a.pdf) replaces the exhaustive nature of the search from before with a random selection of parameters over the specified space. This method can outperform GridSearch in cases where the number of parameters affecting the model's performance is small (low-dimension optimization problems). Since this does not pick every tuple from the cartesian product, it tends to yield results faster, and the performance can be comparable to that of the Grid Search approach. It's worth keeping in mind that the random nature of this search means, the results with each run might differ.\n",
    "\n",
    "Some of the other methods used for HPO include:\n",
    "\n",
    "1. Bayesian Optimization\n",
    "\n",
    "2. Gradient-based Optimization\n",
    "\n",
    "3. Evolutionary Optimization\n",
    "\n",
    "To learn more about HPO, some papers are linked to at the end of the notebook for further reading.\n",
    "\n",
    "Now that we have a basic understanding of what HPO is, let's discuss what we wish to achieve with this demo. The aim of this notebook is to show the importance of hyper parameter optimisation and the performance of dask-ml GPU for xgboost and cuML-RF and compare the performance with the dask-ml CPU version. We'll highlight the improvements in model performance and the run-time for Grid and Random searches in the CPU and GPU versions.\n",
    "\n",
    "We make use of the [Higgs dataset](https://archive.ics.uci.edu/ml/datasets/HIGGS). It solves a binary classification problem to distinguish between signal processes that produce Higgs bosons from those that do not. There are a total of 28 features, first 21 are measured and the last 7 are functions of these. It has 11 Million entries.\n",
    "\n",
    "Let's get started!"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "import warnings\n",
    "warnings.filterwarnings('ignore') # Reduce number of messages/warnings displayed"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [],
   "source": [
    "import time\n",
    "\n",
    "import numpy as np\n",
    "import cupy as cp\n",
    "import pandas as pd\n",
    "\n",
    "import cudf\n",
    "import cuml\n",
    "import rmm\n",
    "import xgboost as xgb\n",
    "\n",
    "import sklearn.model_selection as sk\n",
    "import dask_ml.model_selection as dcv\n",
    "from dask.distributed import Client, wait\n",
    "from dask_cuda import LocalCUDACluster\n",
    "\n",
    "from sklearn import datasets\n",
    "from sklearn.metrics import make_scorer\n",
    "from sklearn.metrics import accuracy_score as sk_acc\n",
    "\n",
    "from cuml.neighbors import KNeighborsClassifier\n",
    "from cuml.preprocessing.model_selection import train_test_split\n",
    "from cuml.metrics.accuracy import accuracy_score\n",
    "\n",
    "import os\n",
    "from urllib.request import urlretrieve\n",
    "import gzip"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Spinning up a CUDA Cluster\n",
    "\n",
    "We start a local cluster and keep it ready for running distributed tasks with dask.\n",
    "\n",
    "\n",
    "[LocalCUDACluster](https://github.com/rapidsai/dask-cuda) launches one Dask worker for each GPU in the current systems. It's developed as a part of the RAPIDS project.\n",
    "Learn More:\n",
    "- [Setting up Dask](https://docs.dask.org/en/latest/setup.html)\n",
    "- [Dask Client](https://distributed.dask.org/en/latest/client.html)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<table style=\"border: 2px solid white;\">\n",
       "<tr>\n",
       "<td style=\"vertical-align: top; border: 0px solid white\">\n",
       "<h3 style=\"text-align: left;\">Client</h3>\n",
       "<ul style=\"text-align: left; list-style: none; margin: 0; padding: 0;\">\n",
       "  <li><b>Scheduler: </b>tcp://127.0.0.1:45309</li>\n",
       "  <li><b>Dashboard: </b><a href='http://127.0.0.1:8005/status' target='_blank'>http://127.0.0.1:8005/status</a>\n",
       "</ul>\n",
       "</td>\n",
       "<td style=\"vertical-align: top; border: 0px solid white\">\n",
       "<h3 style=\"text-align: left;\">Cluster</h3>\n",
       "<ul style=\"text-align: left; list-style:none; margin: 0; padding: 0;\">\n",
       "  <li><b>Workers: </b>4</li>\n",
       "  <li><b>Cores: </b>4</li>\n",
       "  <li><b>Memory: </b>404.27 GB</li>\n",
       "</ul>\n",
       "</td>\n",
       "</tr>\n",
       "</table>"
      ],
      "text/plain": [
       "<Client: 'tcp://127.0.0.1:45309' processes=4 threads=4, memory=404.27 GB>"
      ]
     },
     "execution_count": 3,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "cluster = LocalCUDACluster(dashboard_address=\"127.0.0.1:8005\")\n",
    "client = Client(cluster)\n",
    "\n",
    "client"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Data Preparation\n",
    "\n",
    "We download the Higgs dataset and decompress the file for reading it in as input. We also assign appropriate column names and dtypes."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [],
   "source": [
    "def download_higgs(compressed_filepath, decompressed_filepath):\n",
    "    higgs_url = 'https://archive.ics.uci.edu/ml/machine-learning-databases/00280/HIGGS.csv.gz'\n",
    "    if not os.path.isfile(compressed_filepath):\n",
    "        urlretrieve(higgs_url, compressed_filepath)\n",
    "    if not os.path.isfile(decompressed_filepath):\n",
    "        cf = gzip.GzipFile(compressed_filepath)\n",
    "        with open(decompressed_filepath, 'wb') as df:\n",
    "            df.write(cf.read())"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [],
   "source": [
    "data_dir = '/home/hyperopt/data/'\n",
    "if not os.path.exists(data_dir):\n",
    "    print('creating data directory')\n",
    "    os.system('mkdir /home/data/')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [],
   "source": [
    "compressed_filepath = os.path.join(data_dir, 'HIGGS.csv.gz') # Set this as path for gzipped Higgs data file, if you already have\n",
    "decompressed_filepath = os.path.join(data_dir, 'HIGGS.csv') # Set this as path for decompressed Higgs data file, if you already have\n",
    "\n",
    "# Uncomment this line to download the dataset.\n",
    "# download_higgs(compressed_filepath, decompressed_filepath)\n",
    "\n",
    "col_names = ['label'] + [\"col-{}\".format(i) for i in range(2, 30)] # Assign column names\n",
    "dtypes_ls = ['int32'] + ['float32' for _ in range(2, 30)] # Assign dtypes to each column\n",
    "input_data = cudf.read_csv(decompressed_filepath, names=col_names, dtype=dtypes_ls)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [],
   "source": [
    "labels = input_data.label.reset_index().drop(['index'], axis=1)\n",
    "for col in labels.columns:\n",
    "    labels[col] = labels[col].astype('float32')\n",
    "data = input_data.drop(['label'], axis=1)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "11000000"
      ]
     },
     "execution_count": 8,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "len(data)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [],
   "source": [
    "import time\n",
    "from contextlib import contextmanager\n",
    "# Helping time blocks of code\n",
    "@contextmanager\n",
    "def timed(txt):\n",
    "    t0 = time.time()\n",
    "    yield\n",
    "    t1 = time.time()\n",
    "    print(\"%32s time:  %8.5f\" % (txt, t1 - t0))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Data Fraction\n",
    "\n",
    "We will make use of `data_fraction` variable that takes value between `(0, 1.0]` to specify the fraction of data to make use. The CPU version crashes when it makes use of larger portion of the dataset, so we will not run the CPU version for a fraction more than `0.1`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [],
   "source": [
    "data_fraction = 0.1"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "1100000\n"
     ]
    }
   ],
   "source": [
    "N_ROWS = int(len(data) * data_fraction)\n",
    "\n",
    "# Define some default values to make use of across the notebook for a fair comparison\n",
    "N_FOLDS = 5\n",
    "N_ESTIMATORS = 100\n",
    "MAX_DEPTH = 5\n",
    "N_ITER = 100\n",
    "print(N_ROWS)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [],
   "source": [
    "data = data[:N_ROWS]\n",
    "labels = labels[:N_ROWS]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Splitting Data\n",
    "\n",
    "We split the data randomnly into train and test sets using the [cuml train_test_split](https://docs.rapids.ai/api/cuml/stable/api.html#cuml.preprocessing.model_selection.train_test_split) and create CPU versions of the data."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [],
   "source": [
    "X_train, X_test, y_train, y_test = train_test_split(data,\n",
    "                                                    labels,\n",
    "                                                    test_size=0.2)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {},
   "outputs": [],
   "source": [
    "X_cpu = X_train.to_pandas()\n",
    "y_cpu = y_train.label.to_numpy()\n",
    "\n",
    "\n",
    "X_test_cpu = X_test.to_pandas()\n",
    "y_test_cpu = y_test.label.to_numpy()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Setup Custom cuML scorers\n",
    "\n",
    "The search functions (such as GridSearchCV) for scikit-learn and dask-ml expect the metric functions (such as accuracy_score) to match the “scorer” API. This can be achieved using the scikit-learn's [make_scorer](https://scikit-learn.org/stable/modules/generated/sklearn.metrics.make_scorer.html) function.\n",
    "\n",
    "We will generate a `cuml_scorer` with the cuML `accuracy_score` function.  You'll also notice an `accuracy_score_wrapper` which primarily converts the y label into a `float32` type. This is because some cuML models only accept this type for now and in order to make it compatible, we perform this conversion.\n",
    "\n",
    "We also create helper functions for performing HPO in 4 different modes: \n",
    "1. `gpu-grid`: Perform GPU based GridSearchCV\n",
    "2. `gpu-random`: Perform GPU based RandomizedSearchCV\n",
    "3. `cpu-grid`: Perform CPU based GridSearchCV\n",
    "4. `cpu-random`: Perform CPU based RandomizedSearchCV"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {},
   "outputs": [],
   "source": [
    "def accuracy_score_wrapper(y, y_hat): \n",
    "    \"\"\"\n",
    "        A wrapper function to convert labels to float32, \n",
    "        and pass it to accuracy_score.\n",
    "        \n",
    "        Params:\n",
    "        - y: The y labels that need to be converted\n",
    "        - y_hat: The predictions made by the model\n",
    "    \"\"\"\n",
    "    y = y.astype(\"float32\") # cuML RandomForest needs the y labels to be float32\n",
    "    return accuracy_score(y, y_hat, convert_dtype=True)\n",
    "\n",
    "accuracy_wrapper_scorer = make_scorer(accuracy_score_wrapper)\n",
    "cuml_accuracy_scorer = make_scorer(accuracy_score, convert_dtype=True)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "metadata": {},
   "outputs": [],
   "source": [
    "def do_HPO(model, gridsearch_params, scorer, X, y, mode='gpu-Grid', n_iter=10):\n",
    "    \"\"\"\n",
    "        Perform HPO based on the mode specified\n",
    "        \n",
    "        mode: default gpu-Grid. The possible options are:\n",
    "        1. gpu-grid: Perform GPU based GridSearchCV\n",
    "        2. gpu-random: Perform GPU based RandomizedSearchCV\n",
    "        3. cpu-grid: Perform CPU based GridSearchCV\n",
    "        4. cpu-random: Perform CPU based RandomizedSearchCV\n",
    "        \n",
    "        n_iter: specified with Random option for number of parameter settings sampled\n",
    "        \n",
    "        Returns the best estimator and the results of the search\n",
    "    \"\"\"\n",
    "    if mode == 'cpu-grid':\n",
    "        print(\"cpu-grid selected\")\n",
    "        clf = dcv.GridSearchCV(model,\n",
    "                              gridsearch_params,\n",
    "                              cv=N_FOLDS,\n",
    "                              scoring=scorer)\n",
    "    elif mode == 'gpu-grid':\n",
    "        print(\"gpu-grid selected\")\n",
    "        clf = dcv.GridSearchCV(model,\n",
    "                               gridsearch_params,\n",
    "                               cv=N_FOLDS,\n",
    "                               scoring=scorer)\n",
    "    elif mode == 'gpu-random':\n",
    "        print(\"gpu-random selected\")\n",
    "        clf = dcv.RandomizedSearchCV(model,\n",
    "                               gridsearch_params,\n",
    "                               cv=N_FOLDS,\n",
    "                               scoring=scorer,\n",
    "                               n_iter=n_iter)\n",
    "    elif mode == 'cpu-random':\n",
    "        print(\"cpu-random selected\")\n",
    "        clf = dcv.RandomizedSearchCV(model,\n",
    "                               gridsearch_params,\n",
    "                               cv=N_FOLDS,\n",
    "                               scoring=scorer,\n",
    "                               n_iter=n_iter)\n",
    "    else:\n",
    "        print(\"Unknown Option, please choose one of [gpu-grid, gpu-random, cpu-grid, cpu-random]\")\n",
    "        return None, None\n",
    "    res = clf.fit(X, y)\n",
    "    print(\"Best clf and score {} {}\\n---\\n\".format(res.best_estimator_, res.best_score_))\n",
    "    return res.best_estimator_, res"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "metadata": {},
   "outputs": [],
   "source": [
    "def print_acc(model, X_train, y_train, X_test, y_test, mode_str=\"Default\"):\n",
    "    \"\"\"\n",
    "        Trains a model on the train data provided, and prints the accuracy of the trained model.\n",
    "        mode_str: User specifies what model it is to print the value\n",
    "    \"\"\"\n",
    "    y_pred = model.fit(X_train, y_train).predict(X_test)\n",
    "    score = accuracy_score(y_pred, y_test.astype('float32'), convert_dtype=True)\n",
    "    \n",
    "    print(\"{} model accuracy: {}\".format(mode_str, score))\n",
    "                                         "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(880000, 28)"
      ]
     },
     "execution_count": 18,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "X_train.shape"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Launch HPO\n",
    "\n",
    "We will first see the model's performances without the gridsearch and then compare it with the performance after searching.\n",
    "\n",
    "### XGBoost\n",
    "\n",
    "To perform the Hyperparameter Optimization, we make use of the sklearn version of the [XGBClassifier](https://xgboost.readthedocs.io/en/latest/python/python_api.html#module-xgboost.sklearn).We're making use of this version to make it compatible and easily comparable to the scikit-learn version. The model takes a set of parameters that can be found in the documentation. We're primarily interested in the `max_depth`, `learning_rate`, `min_child_weight`, `reg_alpha` and `num_round` as these affect the performance of XGBoost the most.\n",
    "\n",
    "Read more about what these parameters are useful for [here](https://xgboost.readthedocs.io/en/latest/parameter.html)\n",
    "\n",
    "We'll first perform the GPU version and then compare it with how long CPU version took to run. We will run only the `dask-ml` GridSearch and RandomSearch in this notebook.\n",
    "\n",
    "\n",
    "#### Default Performance\n",
    "\n",
    "We first use the model with it's default parameters and see the accuracy of the model. In this case, it is 71%"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Default model accuracy: 0.7132499814033508\n"
     ]
    }
   ],
   "source": [
    "model_gpu_xgb_ = xgb.XGBClassifier(tree_method='gpu_hist')\n",
    "\n",
    "print_acc(model_gpu_xgb_, X_train, y_cpu, X_test, y_test_cpu)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Parameter Distributions\n",
    "\n",
    "The way we define the grid to perform the search is by including ranges of parameters that need to be used for the search. In this example we make use of [np.arange](https://docs.scipy.org/doc/numpy/reference/generated/numpy.arange.html) which returns an ndarray of even spaced values, [np.logspace](https://docs.scipy.org/doc/numpy/reference/generated/numpy.logspace.html#numpy.logspace) returns a specified number of ssamples that are equally spaced on the log scale. We can also specify as lists, NumPy arrays or make use of any random variate sample that gives a sample when called. SciPy provides various functions for this too."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 20,
   "metadata": {},
   "outputs": [],
   "source": [
    "# For xgb_model\n",
    "model_gpu_xgb = xgb.XGBClassifier(tree_method='gpu_hist')\n",
    "\n",
    "# More range \n",
    "params_xgb = {\n",
    "    \"max_depth\": np.arange(start=3, stop = 15, step = 3), # Default = 6\n",
    "    \"alpha\" : np.logspace(-3, -1, 5), # default = 0\n",
    "    \"learning_rate\": [0.05, 0.1, 0.15], #default = 0.3\n",
    "    \"min_child_weight\" : np.arange(start=2, stop=10, step=3), # default = 1\n",
    "    \"n_estimators\": [100, 200, 1000]\n",
    "}"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### RandomizedSearchCV\n",
    "\n",
    "We'll now try [RandomizedSearchCV](https://dask-ml.readthedocs.io/en/latest/modules/generated/dask_ml.model_selection.RandomizedSearchCV.html).\n",
    "`n_iter` specifies the number of parameters points theat the search needs to perform. Here we will search `N_ITER` (defined earlier) points for the best performance."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 21,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "gpu-random selected\n",
      "Best clf and score XGBClassifier(alpha=0.001, base_score=0.5, booster='gbtree',\n",
      "              colsample_bylevel=1, colsample_bynode=1, colsample_bytree=1,\n",
      "              gamma=0, gpu_id=-1, learning_rate=0.05, max_delta_step=0,\n",
      "              max_depth=12, min_child_weight=2, missing=nan, n_estimators=1000,\n",
      "              n_jobs=1, objective='binary:logistic', random_state=0,\n",
      "              reg_alpha=0, reg_lambda=1, scale_pos_weight=1, subsample=1,\n",
      "              tree_method='gpu_hist', verbose=1) 0.7502772559810091\n",
      "---\n",
      "\n",
      "                  XGB-gpu-random time:  2124.28109\n",
      "Searched over 100 parameters\n"
     ]
    }
   ],
   "source": [
    "mode = \"gpu-random\"\n",
    "\n",
    "with timed(\"XGB-\"+mode):\n",
    "    res, results = do_HPO(model_gpu_xgb,\n",
    "                                   params_xgb,\n",
    "                                   cuml_accuracy_scorer,\n",
    "                                   X_train,\n",
    "                                   y_cpu,\n",
    "                                   mode=mode,\n",
    "                                   n_iter=N_ITER)\n",
    "print(\"Searched over {} parameters\".format(len(results.cv_results_['mean_test_score'])))\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 22,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "gpu-random model accuracy: 0.7528954744338989\n"
     ]
    }
   ],
   "source": [
    "print_acc(res, X_train, y_cpu, X_test, y_test_cpu, mode_str=mode)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 21,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "gpu-grid selected\n",
      "Best clf and score XGBClassifier(alpha=0.1, base_score=0.5, booster='gbtree', colsample_bylevel=1,\n",
      "              colsample_bynode=1, colsample_bytree=1, gamma=0, gpu_id=-1,\n",
      "              learning_rate=0.05, max_delta_step=0, max_depth=12,\n",
      "              min_child_weight=5, missing=nan, n_estimators=1000, n_jobs=1,\n",
      "              objective='binary:logistic', random_state=0, reg_alpha=0,\n",
      "              reg_lambda=1, scale_pos_weight=1, subsample=1,\n",
      "              tree_method='gpu_hist', verbose=1) 0.7508500106381422\n",
      "---\n",
      "\n",
      "                    XGB-gpu-grid time:  11053.56941\n",
      "Searched over 540 parameters\n"
     ]
    }
   ],
   "source": [
    "mode = \"gpu-grid\"\n",
    "\n",
    "with timed(\"XGB-\"+mode):\n",
    "    res, results = do_HPO(model_gpu_xgb,\n",
    "                                   params_xgb,\n",
    "                                   cuml_accuracy_scorer,\n",
    "                                   X_train,\n",
    "                                   y_cpu,\n",
    "                                   mode=mode)\n",
    "print(\"Searched over {} parameters\".format(len(results.cv_results_['mean_test_score'])))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 22,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "gpu-grid model accuracy: 0.7526272535324097\n"
     ]
    }
   ],
   "source": [
    "print_acc(res, X_train, y_cpu, X_test, y_test_cpu, mode_str=mode)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Improved performance\n",
    "\n",
    "There's a 4% improvement in the performance.\n",
    "\n",
    "We notice that performing grid search and random search yields similar performance improvements. We will stick to performing Random Search for the rest of the notebook with the other classifiers with the assumption that there will not be a major difference in performance if the ranges are large enough. \n",
    "\n",
    "In order to compare the running time, we will also run the CPU version of this later in the notebook to see what timing improvements look like."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Visualizing the Search\n",
    "\n",
    "Let's plot some graphs to get an understanding how the parameters affect the accuracy. The code for these plots are included in `cuml/experimental/hyperopt_utils/plotting_utils.py`"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Mean/Std of test scores\n",
    "\n",
    "We fix all parameters except one for each of these graphs and plot the effect the parameter has on the mean test score with the error bar indicating the standard deviation"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 23,
   "metadata": {},
   "outputs": [],
   "source": [
    "from cuml.experimental.hyperopt_utils import plotting_utils"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 24,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "image/png": "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a9eyatUqFi1axHPPPccnn3yCtZaLLrqI999/n3379pGZmclrr70GQHl5OfHx8fzyl7/knXfeISUlpX0OUCREAZ2IiIiIiIiIOKalseUuOKUP10zJ4b6FG6iu8zdbV13n565X1jEvL4sDlT6+8eTyZuuPp3HIokWLWLRoEXl5eQAcOnSIzZs3M336dL7//e9z2223ccEFFzB9+vQTODKRY6eATkRERERERES6pN3lNS0uL6uqa5f9W2tZsGABt9xyyxHrli9fzuuvv86CBQs499xzufPOO9vlNUVaooBORERERER6PA27ItJ1tXVeZiZEUlRWfcTyrIRIAJKivcd9XsfGxlJRUQHArFmzuOOOO7jqqquIiYmhqKgIj8dDfX09SUlJXH311cTExPDYY481e666uEp7U0AnIj3SiyuLuPW51fj8AbISIk96INmupqcfn4iIdC69r8iJ0u+OdLT5s4ay4IU1zbq5RnrczJ819IT3mZyczNSpUxk1ahRz5szhyiuvZMqUYMgXExPDk08+yZYtW5g/fz4ulwuPx8Mf/vAHAG6++WbmzJlDnz59NElEL9YRf/sU0MlR6W6jdDcdMZBsV9LTj09ERDqX3lfkROl3p3P09s9jDb9L7R2GPP30080ef/vb3272eODAgcyaNeuI533rW9/iW9/61km9tnRvHfW3TwGdHLfjeYNo7+mwpWfyByzVdX6qauup9PmJ9rpJi4ugzh9g0bpiKn31jeuqfPVMyk3m9CGplFb6+N7fVzUur6r1U+mrp6Yu0OJAsve/sbFH/P7d/8bGFo/vZws39IjjExGRzrGnvIZVO0v54Ytre/T7Zm9mrQXAGENFTR37Kmqp8vmpqfNTXeen2udn+uBUIr1uVhSUsmRrCTW+4Lqq0P8/mTeaSK+bv368neeWFwafF3puySEf9rDXrK7z8/1/fMZfl+wgOdrLw9eMxxjDuxv3sru8hsQoDwlRXpKivSRGeUmNDe/074t0P/PysnjmkwKg9waV0jXsP1TLXa+s65D3TQV00mG6+h213n4n6kRYa/H5A9T5LTHhwT8fa4vKOVhd1xiSHaqtp098BGcNSwfg7lfzOVDpC4ZsvuDF3rRBKXx35hCstYy+axGHauubvc71p+Vw10UjCVjLfz69otk6t8sQ5nJx+pBU3G7D/kM+orxu0mIjiEp2E+0N49ll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\n",
      "text/plain": [
       "<Figure size 1440x360 with 5 Axes>"
      ]
     },
     "metadata": {
      "needs_background": "light"
     },
     "output_type": "display_data"
    }
   ],
   "source": [
    "plotting_utils.plot_search_results(results)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Heatmaps \n",
    "   - Between parameter pairs (we can do a combination of all possible pairs, but only one are shown in this notebook) \n",
    "   - This gives a visual representation of how the pair affect the test score"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 26,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "image/png": "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\n",
      "text/plain": [
       "<Figure size 432x288 with 2 Axes>"
      ]
     },
     "metadata": {
      "needs_background": "light"
     },
     "output_type": "display_data"
    }
   ],
   "source": [
    "df_gridsearch = pd.DataFrame(results.cv_results_)\n",
    "plotting_utils.plot_heatmap(df_gridsearch, \"param_max_depth\", \"param_n_estimators\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### CPU version\n",
    "\n",
    "Now, running the model in CPU version to notice the difference in performance in terms of time. The main difference you would notice is that the `tree_method` is set to `hist` instead of `gpu_hist`. The interface remains the same and we can even make use of the same parameters that we defined earlier (in fact, this is necessary for a fair comparison). \n",
    "\n",
    "Note: Remember the `data_fraction` flag from earlier and we will ensure we only run the CPU version if we are using less than 1% of the data"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 27,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "cpu-random selected\n",
      "Best clf and score XGBClassifier(alpha=0.03162277660168379, base_score=0.5, booster='gbtree',\n",
      "              colsample_bylevel=1, colsample_bynode=1, colsample_bytree=1,\n",
      "              gamma=0, gpu_id=-1, learning_rate=0.05, max_delta_step=0,\n",
      "              max_depth=12, min_child_weight=8, missing=nan, n_estimators=1000,\n",
      "              n_jobs=1, objective='binary:logistic', random_state=0,\n",
      "              reg_alpha=0, reg_lambda=1, scale_pos_weight=1, subsample=1,\n",
      "              tree_method='hist', verbose=1) 0.7507897727272728\n",
      "---\n",
      "\n",
      "                  XGB-cpu-random time:  27485.06421\n",
      "Searched over 100 parameters\n",
      "cpu-random model accuracy: 0.7510272860527039\n"
     ]
    }
   ],
   "source": [
    "if data_fraction <= 0.1:\n",
    "    model_cpu_xgb = xgb.XGBClassifier(tree_method='hist')\n",
    "\n",
    "    mode = \"cpu-random\"\n",
    "    with timed(\"XGB-\" + mode):\n",
    "        res, results = do_HPO(model_cpu_xgb,\n",
    "                   params_xgb,\n",
    "                   'accuracy',\n",
    "                   X_cpu,\n",
    "                   y_cpu,\n",
    "                   mode=mode,\n",
    "                   n_iter=N_ITER)\n",
    "    \n",
    "    print(\"Searched over {} parameters\".format(len(results.cv_results_['mean_test_score'])))\n",
    "    \n",
    "    print_acc(res , X_cpu, y_cpu, X_test_cpu, y_test_cpu,\n",
    "              mode_str=mode)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Remember the GPU version of RandomizedSearch ran in 2124 seconds.\n",
    "\n",
    "And the CPU version took 27485 seconds over the same number of parameters.\n",
    "\n",
    "#### We notice a <b> 13x speed-up </b>. \n",
    "\n",
    "For the rest of the notebook, we will run just the GPU version. You are free to swap out of the mode to CPU options to see what happens with different models.\n",
    "\n",
    "#### Running CPU Modes\n",
    "\n",
    "Each cell that calls this `do_HPO` function has a `mode` variable defining what task we want it to perform. \n",
    "\n",
    "1. For CPU experiments, use `cpu-random` or `cpu-grid` depending of which experiment you wish to run. \n",
    "\n",
    "2. If you make use of `cpu-random`, specify `n_iter` for number of parameter combinations to consider. It defaults to just 10.\n",
    "\n",
    "3. For CPU modes, the scorer we use is the default 'accuracy' metric.\n",
    "\n",
    "<b> DO NOT</b> use `cuml_scorer` or the `accuracy_wrapper_scorer` both of these are used for the GPU options.\n",
    "\n",
    "#### Runtime observations\n",
    "These are the observed runtimes for different runs with different combinations. All of these are run on 4 Tesla T4 GPUs 16GB RAM. You will notice that some of the combinations do not have a CPU runtime comparison, this was intentionally done to avoid the redundancy in experiments and prevent the kernel crashing.\n",
    "\n",
    "| data_fraction | parameters | GPU Time |CPU Time\n",
    "|---------------|------------| ------|---|\n",
    "|0.01|100|258.98545|1131.57301|\n",
    "| |180|380.23315|2079.6394|\n",
    "||240|616.53354|-|\n",
    "|0.1|100|705.42218|9832.40570|\n",
    "||270|1998.64815|-|\n",
    "|0.5|250|4909.64941|-|\n",
    "|0.7|180|5696.12868|-|\n",
    "\n",
    "We are searching over a small space because we want to compare with the CPU version, it is recommended that you change the following values to observe changes in performance:\n",
    "\n",
    "1. `data_fraction` >= 0.5\n",
    "2. Increase parameter ranges to search over 1000 parameters and `N_ITER` >= 400"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### KNNClassifier\n",
    "\n",
    "We are going to now perform HPO with [cuml-KNNClassifier](https://docs.rapids.ai/api/cuml/stable/api.html#cuml.neighbors.KNeighborsClassifier). We will again note the default performance and notice what HPO does to improve this.\n",
    "\n",
    "We will run GridSearch for KNN because we are tuning just one parameter, which is `n_neighbors`, this defines the number of neighbors to consider for the classification.\n",
    "\n",
    "We plot a simple 2D plot to observe the effect of neighbors on accuracy."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 28,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Default accuracy 0.625322699546814\n"
     ]
    }
   ],
   "source": [
    "# KNN-Classifier\n",
    "model_knn_ = KNeighborsClassifier(n_neighbors=5)\n",
    "\n",
    "model_knn_.fit(X_train, y_train)\n",
    "print(\"Default accuracy {}\".format(accuracy_score(model_knn_.predict(X_test), y_test)))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 29,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "gpu-grid selected\n",
      "Best clf and score KNeighborsClassifier(weights='uniform') 0.6498602271080017\n",
      "---\n",
      "\n",
      "                    KNN-gpu-grid time:  351.95597\n"
     ]
    }
   ],
   "source": [
    "model_knn = KNeighborsClassifier(n_neighbors=5)\n",
    "\n",
    "ks = [i for i in range(1, 40)]\n",
    "params_knn = {'n_neighbors': ks\n",
    "             }\n",
    "\n",
    "mode = \"gpu-grid\"\n",
    "with timed(\"KNN-\"+mode):\n",
    "    res, results = do_HPO(model_knn,\n",
    "               params_knn,\n",
    "               cuml_accuracy_scorer,\n",
    "               X_train,\n",
    "               y_cpu.astype('int32'),\n",
    "                mode=mode)\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 30,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "gpu-grid accuracy 0.6510545611381531\n"
     ]
    }
   ],
   "source": [
    "res.fit(X_train, y_train)\n",
    "print(\"{} accuracy {}\".format(mode, accuracy_score(res.predict(X_test), y_test)))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 34,
   "metadata": {},
   "outputs": [],
   "source": [
    "df = pd.DataFrame(results.cv_results_)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 43,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<matplotlib.axes._subplots.AxesSubplot at 0x7fbffde94048>"
      ]
     },
     "execution_count": 43,
     "metadata": {},
     "output_type": "execute_result"
    },
    {
     "data": {
      "image/png": "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\n",
      "text/plain": [
       "<Figure size 432x288 with 1 Axes>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "import seaborn as sns; sns.set()\n",
    "import matplotlib.pyplot as plt\n",
    "sns.lineplot(x=\"param_n_neighbors\", y=\"mean_test_score\", data=df)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We notice a 3% increase in the accuracy. \n",
    "\n",
    "\n",
    "## Conclusion and Next Steps\n",
    "\n",
    "We notice improvements in the performance for a really basic version of the GridSearch and RandomizedSearch on just 10% of the data. Generally, the more data we use, the better the model performs, so you are encouraged to try for larger data and broader range of parameters.\n",
    "\n",
    "This experiment can also be repeated with different classifiers and different ranges of parameters to notice how HPO can help improve the performance metric. In this example, we have chosen a basic metric - accuracy, but you can use more interesting metrics that help in determining the usefulness of a model. You can even send a list of parameters to the scoring function. This makes HPO really powerful, and it can add a significant boost to the model that we generate.\n",
    "\n",
    "\n",
    "#### Further Reading\n",
    "\n",
    "- [The 5 Classification Evaluation Metrics You Must Know](https://towardsdatascience.com/the-5-classification-evaluation-metrics-you-must-know-aa97784ff226)\n",
    "- [11 Important Model Evaluation Metrics for Machine Learning Everyone should know](https://www.analyticsvidhya.com/blog/2019/08/11-important-model-evaluation-error-metrics/)\n",
    "- [Algorithms for Hyper-Parameter Optimisation](http://papers.nips.cc/paper/4443-algorithms-for-hyper-parameter-optimization.pdf)\n",
    "- [Forward and Reverse Gradient-Based Hyperparameter Optimization](http://proceedings.mlr.press/v70/franceschi17a/franceschi17a-supp.pdf)\n",
    "- [Practical Bayesian Optimization of Machine\n",
    "Learning Algorithms](http://papers.nips.cc/paper/4522-practical-bayesian-optimization-of-machine-learning-algorithms.pdf)\n",
    "- [Random Search for Hyper-Parameter Optimization](http://jmlr.csail.mit.edu/papers/volume13/bergstra12a/bergstra12a.pdf)"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.6.7"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}
